/**
*  \file sdstructmgr.h
*
*  \brief Storage Device Structure Manager
*
*  \author Michael J. Hohmann  michael.hohmann@linde-mh.de
*
*	The sdstructmgr provide functions to store and read arbitrarily structures to an storage device in a transaction save way.
*	Therefore several shadow structures are located in the sddevice so that it can be guaranteed that always the latest completely written
*	structure is read.
*
*	Compatibility  expectation:
*	Compiler:   generic
*	CPU:		generic
*	Byte order:	generic
*
*
*  X  X         Undefined
*  A1 X         Invalid
*  A1 B1        Valid
*  A2 B1        Invalid
*  A2 B2        Valid
*
*
*
*
*/
#ifndef SDSTRUCTMGR_H_INCLUDED
#define SDSTRUCTMGR_H_INCLUDED

/*================================================[ public includes  ]================================================*/
#include "../cfg/prj.h"
#include "../sd/sd.h"
/*================================================[ public defines   ]================================================*/


/*================================================[ public datatypes ]================================================*/

/** Management structure.
*
*  This structure is needed to check which dataset was written last and to check the integrity.
*/
struct sdstructmgr_management
{
   U8  status[2]; /**< Status flags*/
   U16 cks;       /**< Checksum. */
   U32 count;     /**< will indicate which dataset was written last */
};

/** Object definition.
* 
* The struct sdstructmgr_obj defines the attribute of an object.
*/
struct sdstructmgr_obj
{	
   struct sd *sdev;                                /**< storage device */
   struct sdstructmgr_management *managment_adr ;  /**< address of the management structure */
   U8  * dataset_adr;   					            /**< address of structs in nv ram */
   pal_size_t dataset_size;                        /**< size of one datastructure */
   pal_size_t dataset_count;                       /**< Number of data structures that are hold in the sd memory*/
   U32 maxcount;                                   /**< count of the latest valid struct */
   pal_size_t valid_index;					            /**< index of the last valid struct */
   //BO found_valid_struct;					            /**< remember if on struct was found valid */

};


/*================================================[ public variables ]================================================*/

/*================================================[ inline functions ]================================================*/

/*================================================[ public functions ]================================================*/

/**
*  Constructor.
*
*
*  If no valid parameter is found in the nv-memory the module uses the parameter default_value to start and the errorcode
*  RC_ERROR_READ_FAILS is returned.
*
*   - initialze object
*   - read the structures in nv-memory until a valid structure was found.
*       if the following structure is also valid mark the first as expired and use the second one.
*
*  \param me Object pointer. NULL will throw an assert.
*  \param sd Pointer to an storage device.
*  \param management_adr start address of an array of management objects hold in the storage device
*  \param dataset_adr start address of an array of structures hold in the storage device
*  \param dataset_size size in bytes of one dataset.
*  \param dataset_count Number of datasets and management obejcts hold in the storage device.

*  \return - RC_SUCCESS if successful.
*          - RC_ERROR if an error occurs.
*/
RC sdstructmgr_construct(
    struct sdstructmgr_obj *me,
    struct sd *sdev,
    struct sdstructmgr_management* management_adr,
	void  * dataset_adr,
    pal_size_t dataset_size,
	pal_size_t detaset_count
);

/** Read latest valid dataset.
*
* \param me Object pointer. NIL will throw an ASSERT.
* \param dataset Pointer to a memory object of size passed at sdstructmgr_construct() as parameter dataset_size.
*                If read data will be stored a this address. NIL will throw an ASSERT.
* \return RC_SUCCESS if a valid structure could be read.
*         RC_ERROR if no sturcture could be read.
*
*/
RC sdstructmgr_get( struct sdstructmgr_obj *me, void * dataset );

/** Write a dataset
*
* \param me Object pointer. NIL will throw an ASSERT.
* \param dataset Pointer to a dataset that should be stored in the storage device. NIL will throw an ASSERT.
*                The size of this dataset is assumed as the value passed at sdstructmgr_construct() as parameter dataset_size.
*/
void sdstructmgr_set( struct sdstructmgr_obj *me, void const* dataset );



/*====================================================================================================================*/

#endif

/***********************************************************************************************************************
*                             Copyright 2018 Linde Material Handling. All rights reserved.                             *
***********************************************************************************************************************/
